classdef dotsFiniteDimension
    % @class dotsFiniteDimension
    % Represents and accounts for a dimension in space.
    % @details
    % Each dotsFiniteDimension object represents one dimension of a finite,
    % discrete space.  It includes constraining properties, such as minimum
    % and maximum value, and number of points.  It also includes
    % descriptive properties, including an integer ID and a string name.
    % @details
    % An array of dotsFiniteDimension objects may be taken to represent an
    % imaginary space or subspace, with orthogonal dimensions each
    % described by an array element.
    % @details
    % dotsQueryable and dotsPhenomenon use dotsFiniteDimension to represent
    % the dimensions of "data space" or "phenomenon space" in a uniform
    % way.
    % @ingroup queryable
    
    properties
        % a string name to describe this dimension
        name = '';
        
        % an integer, reasonably unique identifier for this dimension
        ID = [];
        
        % the finite number of points along this dimension
        size = [];
        
        % the minimum value of interest than may fall on this dimension
        minValue = [];
        
        % the maximum value of interest than may fall on this dimension
        maxValue = [];
        
        % an array of evenly values spanning minValue and maxValue,
        % and containing size number of elements
        values = [];
        
        % the least surprising or least informative element of values, safe
        % to use as a default
        neutralValue = [];
        
        % an array of indexes into values, indicating a selection or range
        % of interest
        indexes = [];
    end
    
    methods
        function d = dotsFiniteDimension
        end
    end
    
    methods (Static)
        % Create a new dotsFiniteDimension object with linearly spaced
        % values.
        % @param minimum the least value of interest
        % @param maximum the greatest value of interest
        % @param size the number of linearly spaced values
        % @details
        % Returns a new dotsFiniteDimension object with values filled in
        % that span @a minimum and @a maximum using @a size linearly spaced
        % points.
        % @details
        % By default indexes will be filled in to include all values.
        function d = newLinear(minimum, maximum, size)
            d = dotsFiniteDimension;
            d.minValue = minimum;
            d.maxValue = maximum;
            d.size = size;
            d.values = linspace(d.minValue, d.maxValue, d.size);
            d.indexes = 1:d.size;
        end
        
        % Create a new dotsFiniteDimension object with arbitrarily spaced
        % values.
        % @param values an array of arbitrary values in the dimension
        % @details
        % Returns a new dotsFiniteDimension that contains the given @a
        % values.  The @a values will be sorted.
        % @details
        % By default indexes will be filled in to include all values.
        function d = newWithValues(values)
            d = dotsFiniteDimension;
            d.values = sort(values);
            d.minValue = d.values(1);
            d.maxValue = d.values(end);
            d.size = numel(d.values);
            d.indexes = 1:d.size;
        end
    end
end